openarenafandomcom-20200216-history
Mapping manual/Compiling and packaging
After all the hard work and testing done with our map, it's time to prepare and package it. In this page, we'll take a look at Q3Map2, BSPC and how to package our map. Before going with the explanation of what each switch and option does, it's highly recommendable to use the latest versions of both BSPC and Q3MAP2. If you're using Q3Radiant, bear in mind that your map may not pass the GPL compliance because it was compiled with a pre-GPL set of compilers (normally the unsupported Q3MAP and an older, pre-GPL version of BSPC). If you don't want to mess with commandlines, there are front-ends at the bottom of the page which may aid you with your compilation tasks. Q3Map2 This is the main utility we're going to use in order to compile our maps. This utility comes with the most recent editors, and its version depends from editor to editor. A full Q3MAP2 compiling consist of BSP, VIS and LIGHT phases. Depending from the stage of development of your map, you may wish to do much faster compiling by omitting some phases for quick testing. For infos about how to speed up compiling by using all of our processor "cores", see Multithreaded map compiling page. The BSP stage The first stage of the map compilation. It generates the .bsp file, the player-navigable space inside the world.SmallPileOfGibs's Q3map explanation How the BSP is created (and how to optimize it) is already covered in the Hint brushes page. Here we're going to mention the switches and what each one of them do. The basic syntax is q3map2 -fs_basepath oadir -fs_game "baseoa" -game "oa" options mapfileroute, where oadir is the directory/folder where OA is installed (i.e. c:\openarena or /home/user/openarena) options are the specified switches, and mapfileroute is the ruote of the .map file to be compiled (i.e. c:\openarena\baseoa\maps\mymap.map or /home/user/openarena/baseoa/maps/mymap.map). The switches of the BSP stage do the following:BSP Stage at Q3Map2 manual in WikibooksBSP stage at Q3Map2 Manual in Shaderlab The VIS stage VIS is short for Visibility. The relevant part of this process is the creation of the PVS Table for the Portals in the map. As the player's viewpoint moves around a FULLY vis'ed bsp different areas become visible or hidden, depending on which area the viewpoint is in. Another stage already explained at the Hint brushes page. Here we're going to mention the switches and what each one of them do.VIS Stage at Q3Map2 manual in WikibooksVIS stage at Q3Map2 Manual in Shaderlab The Light stage This is the lighting stage, where lightmaps are generated for every world surface in the map. It has no effect on bsp, hints, vis or r_speeds. This stage is already explained in the Lighting page. Here we're going to mention the switches and what each one of them do.Light Stage at Q3Map2 manual in WikibooksQ3Map2 Manual at Shaderlab BSPC Also called BSP-to-AAS compiler. This stage uses the bspc tool, and generates an Area file mapname.aas. The Area file is used by bots to navigate the map. BSPC is a separate process from the other compile stages, and and it has no effect on and ignores any information created in those stages. BSPC requires only a mapname.bsp which does not leak. How this stage works is already explained in the bot play page. Here we're going to mention the switches and what they do.GTKR Manual, Appendix C Front-ends These tools do away with the troubles of writing the compilation command lines by using a GUI. * Q3Map2GUI * Q3Map2Build - 1.0 Build 25 Download, with BSPC and required DLL files ** Q3Map2Build tutorial * IoQ3MapTools, by Onykage Some building script examples Remember to replace "/path/to/" and "C:\path\to\" with the routes to your editor installation. Also remember to use the latest versions of both q3map2 and bspc. Test compile script (Windows): "C:\path\to\q3map2.exe" -leaktest -v -verboseentities "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -vis -saveprt -v "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -light -v "C:\path\to\mapname.map" "C:\path\to\bspc.exe" -bsp2aas "C:\path\to\mapname.bsp" Test compile script (Linux): /path/to/q3map2 -leaktest -v -verboseentities /path/to/mapname.map /path/to/q3map2 -vis -saveprt -v /path/to/mapname.map /path/to/q3map2 -light -v /path/to/mapname.map /path/to/bspc -bsp2aas /path/to/mapname.bsp Final compile script (Windows): "C:\path\to\q3map2.exe" -flares -meta -patchmeta -skyfix -v -verboseentities "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -vis -v "C:\path\to\mapname.map" "C:\path\to\q3map2.exe" -light -dark -dirty -fast -patchshadows -v -samples 3 -bounce 8 -gamma 2 -compensate 4 "C:\path\to\mapname.map" "C:\path\to\bspc.exe" -bsp2aas -forcesidesvisible -optimize -grapplereach "C:\path\to\mapname.bsp" Final compile script (Linux): /path/to/q3map2 -flares -meta -patchmeta -skyfix -v -verboseentities /path/to/mapname.map /path/to/q3map2 -vis -v /path/to/mapname.map /path/to/q3map2 -light -dark -dirty -fast -patchshadows -v -samples 3 -bounce 8 -gamma 2 -compensate 4 /path/to/mapname.map /path/to/bspc -bsp2aas -forcesidesvisible -optimize -grapplereach /path/to/mapname.bsp Packaging the map After compiling your map, you need to package it in a way that OA recognizes it as a game package. Game packages have the extension .pk3, and are just renamed zip files.You may need to set your OS to do NOT "hide extensions for known file types". You may also wish to use "maximum" compression instead of standard compression in your zip software, to make the resulting zip/pk3 a little bit smaller. You can pack them the manual way or let a program pack your map for you. This is something you should have considered since the beginning, however don't forget the general rule that your assets (bsp, textures, sounds...) should NOT have the same exact "path+name" of stock OpenArena assets. For shaders, this is true for both shader file name and for every single shader contained. After you finish packaging, it's a good practice to also test your pk3 on a different, "clean" OA installation,If you have a second PC, you may use it. Otherwise, extract OpenArena installation zip to another location of your PC (to have a clean basepath) and launch the game from a different user or manually specifying a non-standard homepath from OS command line (to have a clean homepath). See FAQ#Can I change the directory to where configuration and autodownloaded files are saved? to check you included all the required stuff. Everything has to work with /sv_pure 1. The manual way This is how the package must be built: * The following files should always be included: ** maps/mymap.bsp ** maps/mymap.aas * The levelshot also shows a preview of the level: ** levelshot/mymap.tga or levelshot/mymap.jpg (the first is recommended, created by using apposite "levelshot" command in-game which takes a 128x128 px levelshot from the "info_player_intermission" entity point of view, without HUD - in case you opt for not using that command, try to do not make the image too big, to keep preview loading quick) * The .arena file allows your map to appear in the Skirmish and Create Server menus, and allows it to be votable via GUI. ** scripts/mymap.arena * Additional resources used for the construction of your maps go in these folders, or better in sub-folders of them. Remember to respect the paths or else your map will contain missing assets: ** env/* (for farboxes) ** models/* (for mapmodels) ** music/* (for background music) ** scripts/* (for shaders) ** sound/* (for sounds) ** textures/* (for textures) :::Warning: that "*" does not mean to place "ALL files from that folder" in the pk3, but instead "all your files there which are used by the map" (pay attention to do not inflate the package with useless files from older maps)Also, as you can guess, you should not include files which are already contained in stock OA PK3 files.. To avoid any risk of overriding someone else's one, it is advisable to do not directly include your own scripts/shaderlist.txt file in the pk3You may just list required shader files in your "readme" file or, if you wish to include it, rename it or place it in a different folder. Or you may just let other mappers guess that, since you included some .shader files in the package, they have to add them to their own shaderlist, if they wish to recompile your map.. * For GPL compliance (seen in detail in the Appendix F) you must also include: ** COPYING file (found on the OA folder) ** maps/mymap.map (the .map file for your map) ** For cleanness sake, a separate folder with the sources of the assets you have created, for example: *** .xcf for GIMP-made textures. *** .blend for Blender-made models. * A plain text "readme.txt" file with infos you wish about the map, its author, license name, supported gametypes, known bugs, compiling options used, etc. See also Readme Model. If you distribute the .pk3 inside a .zip file, it is a good practice to place a copy of it inside both of them. To keep the .pk3 filesize smaller, you may opt to distribute it inside a .zip file, and place assets "source" files (e.g. those of textures or sounds) in the zip file instead. In that case, don't forget to include in the .pk3 the infos required to download the complete zip package (example: "Texture sources are available in mymap.zip file which you can download from OpenArena section of www.mysite.com: http://www.mysite.com/openarena/downloads/mymap.zip" inside readme.txt), and a copy of COPYING file in both. Packaging programs There are dedicated packages which package your maps and the used assets for you. These are some of them: * PK3 Creator (internet archive) - Unfornutately, those download links aren't working. * Pakscape - Download version 2 Patching a map package In case you already published your map to the world and later you need to make some fixes to the package (e.g. missing assets such as textures or sounds, errors in .shader or .arena files...), you may either create a "patch" package or a complete "re-release". Each option has some aspects to consider. Notes